@hachej/boring-ui-cli 0.1.13 → 0.1.16

package/README.md

@@ -1,42 +1,235 @@
-# @hachej/boring-ui
+# @hachej/boring-ui-cli
 
-**Turn an agent into an app.**
+<div align="center">
 
-Start a full agent workspace pointed at your current directory — chat, panels, file tree, command palette — in one command.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@hachej/boring-ui-cli.svg)](https://www.npmjs.com/package/@hachej/boring-ui-cli)
+
+</div>
+
+**Turn an agent into an app — in one command.** Start a full IDE-style workbench pointed at your current directory: chat, file tree, editor, command palette. No clone. No database. No config.
 
 ```bash
 npx @hachej/boring-ui-cli
 ```
 
-No config. No clone. No database. Requires an Anthropic API key (or login via Claude/Copilot/Gemini on first run).
+---
+
+## TL;DR
+
+**The Problem**: You want a coding agent in a browser IDE — but you don't want to clone a repo, set up Postgres, configure auth, or deploy anything. You just want to talk to an AI about your code.
+
+**The Solution**: `npx @hachej/boring-ui-cli` starts a full workbench locally, using your current directory as the workspace. It opens a browser tab with chat, file explorer, and panels. Zero setup, zero config, zero deploy.
+
+### Why Use @hachej/boring-ui-cli?
+
+| Feature | What It Does |
+|---------|--------------|
+| **Zero-config startup** | `npx @hachej/boring-ui-cli` — that's it. Opens your browser to a full agent workbench. |
+| **Simple auth** | Set `ANTHROPIC_API_KEY` in your environment. The agent runs with direct filesystem access to your cwd. |
+| **Full workspace** | Chat, file tree, editor panels, command palette — all running against your real directory. |
+| **No database** | Runs in-memory. State persists for the session. No external dependencies. |
+| **Customizable port + root** | `PORT=8080` and `BORING_AGENT_WORKSPACE_ROOT=/path` env vars for power users. |
+
+---
+
+## Quick Example
+
+```bash
+# Navigate to any project
+cd /path/to/my-project
+
+# Start the CLI — opens browser at localhost:5200
+npx @hachej/boring-ui-cli
+
+# With a custom port
+PORT=8080 npx @hachej/boring-ui-cli
+
+# Point at a specific directory
+BORING_AGENT_WORKSPACE_ROOT=/path/to/project npx @hachej/boring-ui-cli
+
+# With API key
+ANTHROPIC_API_KEY=sk-ant-... npx @hachej/boring-ui-cli
+```
+
+Once the browser opens, you can:
+```
+# In the chat box:
+"read my README and suggest improvements"
+"find all TypeScript files that import 'react'"
+"rewrite the test file to use vitest"
+```
 
 ---
 
-## What it starts
+## Installation
+
+No installation needed — use `npx`:
 
-- A chat interface wired to a real coding agent
-- A workspace with panels, a file tree, and a command palette
-- The agent runs with full access to your current directory
+```bash
+npx @hachej/boring-ui-cli
+```
 
-## API key
+Or install globally for repeated use:
+
+```bash
+# npm
+npm install -g @hachej/boring-ui-cli
+
+# pnpm
+pnpm add -g @hachej/boring-ui-cli
+
+# Then just run:
+boring-ui
+```
 
-Set it in your environment:
+### From Source
+
+```bash
+git clone https://github.com/hachej/boring-ui.git
+cd boring-ui && pnpm install
+pnpm --filter @hachej/boring-ui-cli build
+npx ./packages/cli/dist/index.js
+```
+
+---
+
+## Authentication
+
+The CLI talks to Anthropic Claude via the agent runtime. You need a valid API key:
 
 ```bash
 ANTHROPIC_API_KEY=sk-ant-... npx @hachej/boring-ui-cli
 ```
 
-Or run without it — the first launch will open a login prompt to authenticate via Claude, Copilot, Gemini, or Codex. Credentials are stored and reused on future runs.
+Only Anthropic Claude is wired in v1. The agent harness supports other providers via the `AgentHarness` interface, but only Anthropic is implemented.
+
+---
 
 ## Options
 
-```bash
-PORT=8080 npx @hachej/boring-ui-cli          # custom port (default: 5200)
-BORING_AGENT_WORKSPACE_ROOT=/my/project npx @hachej/boring-ui-cli  # custom root
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Anthropic API key. The agent requires a valid key to function. |
+| `PORT` | `5200` | Port to run the server on |
+| `BORING_AGENT_WORKSPACE_ROOT` | `.` (cwd) | Root directory for the workspace. The agent sees this as its filesystem. |
+| `BORING_AGENT_MODE` | `direct` | `direct` (no sandbox) or `local` (bwrap sandbox, Linux only) |
+| `BORING_AGENT_DEFAULT_MODEL_ID` | `claude-sonnet-4-6` | Default model to use |
+
+---
+
+## Architecture
+
+```
+npx @hachej/boring-ui-cli
+  ├── Boot Fastify server (direct mode, in-memory)
+  ├── Serve frontend SPA (Vite-built bundle)
+  ├── Open browser → http://localhost:5200
+  └── Workspace = your current directory (or $BORING_AGENT_WORKSPACE_ROOT)
 ```
 
+The CLI is the zero-config entry point to the full boring-ui stack. Under the hood it wires together:
+
+- `@hachej/boring-agent` — agent runtime, tools, chat UI
+- `@hachej/boring-workspace` — file tree, panels, command palette, plugins
+- `@hachej/boring-ui-kit` — shared UI primitives
+
+All running locally against your real filesystem with no database.
+
+---
+
+## How @hachej/boring-ui-cli Compares
+
+| Feature | @hachej/boring-ui-cli | Claude Code | Codex CLI | Cursor |
+|---------|------------------------|-------------|-----------|--------|
+| Browser UI | ✅ Full IDE with panels | ❌ Terminal only | ❌ Terminal only | ✅ Desktop app |
+| File tree | ✅ Side panel | ❌ | ❌ | ✅ |
+| Zero setup | ✅ `npx` anywhere | ⚠️ Install + login | ⚠️ Install + login | ❌ Desktop app download |
+| Panel system | ✅ Dockview splittable panels | ❌ | ❌ | ❌ |
+| Plugin extensibility | ✅ Panels, commands, catalogs | ❌ | ❌ | ⚠️ Extensions |
+| Local filesystem | ✅ Direct access | ✅ | ✅ | ✅ |
+| Database required | ❌ None | ❌ | ❌ | ❌ |
+
+**When to use @hachej/boring-ui-cli:**
+- You want a browser-based coding agent with file tree and panels
+- You don't want to install anything — just `npx`
+- You want plugin extensibility (custom panels, data catalogs, etc.)
+
+**When it might not fit:**
+- You prefer terminal-only agent workflows (use Claude Code or Codex CLI)
+- You need multi-user auth, workspaces, or a database (use `@hachej/boring-core`)
+- You want a full desktop IDE with LSP, debugging, and git (use Cursor or VS Code)
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ANTHROPIC_API_KEY not set` | No API key | `export ANTHROPIC_API_KEY=sk-ant-...` before running |
+| `port already in use` | Port 5200 occupied | `PORT=5201 npx @hachej/boring-ui-cli` |
+| Browser doesn't open | `BROWSER=none` or no display | Manually navigate to `http://localhost:5200` |
+| Agent returns errors | Invalid API key | Verify your Anthropic API key is valid and has quota |
+| `workspace root not found` | `BORING_AGENT_WORKSPACE_ROOT` points to non-existent dir | Create the directory or unset the variable to use cwd |
+
+---
+
+## Limitations
+
+- **In-memory only**: No database, no persistent workspaces. State is lost when the CLI exits.
+- **Single workspace**: Points at one directory. No multi-workspace switching.
+- **No auth management**: No user accounts, invites, or role-based access.
+- **Direct mode only**: No bwrap sandbox by default (use `BORING_AGENT_MODE=local` on Linux with bubblewrap installed).
+- **Not for production**: This is a developer tool, not a deployment target. Use `@hachej/boring-core` for multi-user apps.
+- **Only Anthropic Claude**: No OpenAI, Google, or other model providers wired in v1.
+
+---
+
+## FAQ
+
+**Q: Do I need to install anything first?**  
+A: No. `npx` downloads and runs the package on first use. Subsequent runs use the cached version.
+
+**Q: What happens when I close the browser?**  
+A: The server keeps running. Stop it with `Ctrl+C` in the terminal.
+
+**Q: Can I use this with OpenAI models?**  
+A: Only Anthropic Claude is wired in v1. Additional providers may be supported in future versions.
+
+**Q: Is my code sent to the cloud?**  
+A: Yes — the agent sends file contents and chat messages to the LLM provider (e.g. Anthropic). The filesystem operations run locally on your machine.
+
+**Q: How is this different from `npx @hachej/boring-agent`?**  
+A: `@hachej/boring-ui-cli` ships the full workbench (file tree, editor, command palette, plugins). `@hachej/boring-agent` is just the agent + chat. The CLI is the batteries-included zero-config entry point.
+
+**Q: Can I extend the CLI with plugins?**  
+A: Not directly in v1. The CLI uses the default agent + workspace configuration. For plugin extensibility, build a custom app using `@hachej/boring-workspace` + `@hachej/boring-core`.
+
+---
+
+## Building Something Bigger?
+
+`@hachej/boring-ui-cli` is the zero-config entry point. For a full app with:
+- Multi-user authentication
+- Persistent workspaces with Postgres
+- Email invites and password resets
+- Custom domain plugins
+
+See the [boring-ui monorepo](https://github.com/hachej/boring-ui) and its packages:
+
+| Package | Purpose |
+|---------|---------|
+| `@hachej/boring-core` | Auth, DB, app factory, multi-user |
+| `@hachej/boring-workspace` | Plugin system, panels, layouts |
+| `@hachej/boring-agent` | Agent runtime, tools, chat UI |
+| `@hachej/boring-ui-kit` | Shared React UI primitives |
+
+---
+
+*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+
 ---
 
-## Building something bigger?
+## License
 
-`@hachej/boring-ui` is the zero-config entry point. For a full app with auth, workspaces, and a database, see the [boring-ui monorepo](https://github.com/hachej/boring-ui).
+MIT

package/dist/index.js

@@ -1,142 +1,14 @@
 #!/usr/bin/env node
-import { createWorkspaceAgentServer } from "@hachej/boring-workspace/app/server";
-import fastifyStatic from "@fastify/static";
-import { AuthStorage, LoginDialogComponent, OAuthSelectorComponent, initTheme } from "@mariozechner/pi-coding-agent";
-import { ProcessTerminal, TUI } from "@mariozechner/pi-tui";
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { createInterface } from "node:readline";
-import { basename, dirname, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
-const { values: args } = parseArgs({
-  options: {
-    port: { type: "string", short: "p" },
-    host: { type: "string" },
-    mode: { type: "string", short: "m" }
-  },
-  strict: false
-});
-const PORT = Number(args.port ?? process.env.PORT) || 5200;
-const HOST = args.host ?? process.env.HOST ?? "0.0.0.0";
-const MODE_MAP = {
-  "local": "direct",
-  // no sandbox, full network access
-  "local-sandbox": "local"
-  // bwrap isolated, no network (Linux only)
-};
-const rawMode = args.mode ?? process.env.BORING_MODE ?? "local-sandbox";
-if (!(rawMode in MODE_MAP)) {
-  console.error(`
-Error: invalid --mode "${rawMode}". Valid options: ${Object.keys(MODE_MAP).join(", ")}
-`);
-  process.exit(1);
-}
-const CLI_MODE = rawMode;
-const MODE = MODE_MAP[CLI_MODE];
+import { runCli } from "./server/cli.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const publicDir = resolve(__dirname, "..", "public");
-const workspaceRoot = process.env.BORING_AGENT_WORKSPACE_ROOT ?? process.cwd();
-const projectName = basename(resolve(workspaceRoot)) || "workspace";
-if (!existsSync(publicDir)) {
-  console.error("\nError: boring-ui frontend not found.");
-  console.error("Run `pnpm build:full` in packages/cli to build it first.\n");
-  process.exit(1);
-}
-function openBrowser(url) {
-  try {
-    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    execSync(`${opener} ${url}`, { stdio: "ignore" });
-  } catch {
-  }
-}
-async function loginWithPi(auth) {
-  const term = new ProcessTerminal();
-  const tui = new TUI(term, false);
-  initTheme("dark");
-  tui.start();
-  const providerId = await new Promise((resolve2, reject) => {
-    const selector = new OAuthSelectorComponent(
-      "login",
-      auth,
-      resolve2,
-      () => reject(new Error("Login cancelled"))
-    );
-    tui.addChild(selector);
-    tui.setFocus(selector);
-    tui.requestRender();
-  });
-  await new Promise((resolve2, reject) => {
-    const dialog = new LoginDialogComponent(tui, providerId, (success) => {
-      success !== false ? resolve2() : reject(new Error("Login cancelled"));
-    });
-    tui.addChild(dialog);
-    tui.setFocus(dialog);
-    tui.requestRender();
-    auth.login(providerId, {
-      onAuth: ({ url }) => {
-        openBrowser(url);
-        dialog.showAuth(url, "Your browser should open automatically. Waiting for login\u2026");
-      },
-      onProgress: (msg) => dialog.showProgress(msg),
-      onPrompt: ({ message }) => new Promise((res) => {
-        dialog.showManualInput(message);
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.question("", (code) => {
-          rl.close();
-          res(code.trim());
-        });
-      })
-    }).catch(reject);
+try {
+  await runCli({
+    argv: process.argv.slice(2),
+    publicDir: resolve(__dirname, "..", "public")
   });
-  tui.stop();
-  term.stop();
-}
-async function resolveApiKey() {
-  if (process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY;
-  const auth = AuthStorage.create();
-  await auth.reload();
-  const stored = await auth.getApiKey("anthropic");
-  if (stored) return stored;
-  console.log("\nNo API key found \u2014 launching login\u2026\n");
-  await loginWithPi(auth);
-  const key = await auth.getApiKey("anthropic");
-  if (!key) {
-    console.error("\nLogin failed. Set ANTHROPIC_API_KEY manually.\n");
-    process.exit(1);
-  }
-  return key;
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
 }
-const apiKey = await resolveApiKey();
-process.env.ANTHROPIC_API_KEY = apiKey;
-console.log(`
-${projectName}`);
-console.log(`  workspace  ${workspaceRoot}`);
-console.log(`  mode       ${CLI_MODE}`);
-console.log(`  port       ${PORT}`);
-console.log(`  host       ${HOST}`);
-const app = await createWorkspaceAgentServer({
-  workspaceRoot,
-  mode: MODE,
-  logger: false
-});
-app.get("/api/v1/workspace/meta", async () => ({
-  workspaceRoot,
-  projectName
-}));
-await app.register(fastifyStatic, {
-  root: publicDir,
-  prefix: "/",
-  wildcard: false
-});
-app.setNotFoundHandler(async (req, reply) => {
-  if (req.url.startsWith("/api/")) {
-    return reply.code(404).send({ error: "Not found" });
-  }
-  return reply.sendFile("index.html", publicDir);
-});
-await app.listen({ port: PORT, host: HOST });
-console.log(`
-  http://localhost:${PORT}
-`);
-openBrowser(`http://localhost:${PORT}`);